home *** CD-ROM | disk | FTP | other *** search
/ Alles Voor Internet / Tout Pour Internet / alles voor internet.iso / MacInternet™ / Telnet / NCSA / tn3270 2.3d26 source / tn3270 / sppc.h < prev    next >
Text File  |  1991-05-28  |  5KB  |  105 lines
  1. /* Definitions for SPPC interface functions */
  2.  
  3. /* Note: The SPPC driver is loaded and opened by SPPCinit at boot time,
  4.          and is intended remain open at all times.  There should be
  5.          no need for an application to open or close the driver.  If
  6.          the driver is not loaded and open, errors in addition to
  7.          those listed below may be returned.                        */
  8.  
  9. OSErr SPPCRegister(unsigned char *myName, short *myRefNum);
  10. /* This call tells the SPPC driver that an application is a client.
  11.    The driver returns a unique refnum which is used for all future
  12.    calls.  The name should be unique for this application. A good
  13.    choice for the name would be the application's signature.  Only
  14.    the first 32 characters of the name are significant.
  15.    
  16.    Errors:
  17.    bdNamErr: length of myName is 0
  18.    dupFNErr: name is already in use
  19.    dirFulErr: maximum number of clients already registered
  20.                                                                        */
  21.  
  22. OSErr SPPCDeRegister(short myRefNum);
  23. /* Before quitting, an application should call SPPCDeRegister to tell
  24.    the driver it is no longer a client.  The reference number for
  25.    the application will become invalid, and any messages queued for
  26.    it will be deleted.
  27.    
  28.    Errors:
  29.    rfNumErr: myRefNum is not assigned to any application
  30.                                                                        */
  31.                                                                 
  32. OSErr SPPCLookup(unsigned char *appName, short *itsRefNum);
  33. /* This call is used to lookup the refnum of another application,
  34.    so that messages may be sent to it.
  35.    
  36.    Errors:
  37.    bdNamErr: length of appName is 0
  38.    fnfErr: no application having appName was found
  39.                                                                        */
  40.                                                                     
  41. OSErr SPPCSend(short myRefNum, short toRefNum,
  42.               unsigned long replyId, Handle theMessage,
  43.               unsigned short msgLength, unsigned long *msgId);
  44. /* This call sends a message to the application specified in toRefNum.
  45.    The data passed in theMessage is copied into the driver's message
  46.    queue, so the memory can be reused after this call returns.  The
  47.    driver assigns a unique id to the message, which it returns in
  48.    msgId.  This id may be used to delete the message before the
  49.    target application receives it.  The length of the message must
  50.    be between 1 and 128.  The sender may use replyId to indicate
  51.    this message is a reply to a previous message.  When replyId is
  52.    not used it must be set to zero.
  53.    
  54.    Errors:
  55.    rfNumErr: myRefNum or toRefNum is not assigned to any application
  56.    memSCErr: message length is invalid, or larger than the handle size
  57.    dirFulErr: maximum number of messages already queued
  58.                                                                        */
  59.                                                                     
  60. OSErr SPPCGet(short myRefNum, short *fromRefNum,
  61.              unsigned long replyId, Handle theMessage,
  62.              unsigned short *msgLength, unsigned long *msgId,
  63.              unsigned long *replyIdPtr);
  64. /* This call gets a message from another application.  The message
  65.    data is copied into the storage pointed to by the handle the
  66.    caller provides.  The reference number of the sending application
  67.    is stored in fromRefNum, the message length is stored in msgLength,
  68.    and the unique id for this message is stored in msgId.  The reply
  69.    id provided by the sender is stored using replyIdPtr.
  70.    Messages are guaranteed to be delivered to an application in the
  71.    order they were sent.
  72.    The driver retains a message until it is successfully received,
  73.    or it has been deleted.
  74.    Use of replyId is optional.  If replyId is specified, only messages
  75.    sent with a corresponding replyId will be received.  If repyId is
  76.    not used, it must be set to 0.
  77.    When the error "memSCErr" is returned, all result variables
  78.    are set except the message data.  
  79.    Note that the caller must allocate sufficient storage for
  80.    receiving the message.  The longest possible message is 128 bytes.
  81.     
  82.    Errors:
  83.    rfNumErr: myRefNum not assigned to any application
  84.    fnfErr: no message found for the caller
  85.    memSCErr: message is too long to fit in the handle provided
  86.                                                                        */
  87.  
  88. OSErr SPPCClear(short myRefNum);
  89. /* This call clears all pending messages for the application assigned
  90.    myRefNum.  This call is implicitly made by SPPCDeRegister.
  91.    
  92.    Errors:
  93.    rfNumErr: myRefNum not assigned to any application
  94.                                                                        */
  95.                                                                     
  96. OSErr SPPCDeleteMsg(unsigned long *msgId);
  97. /* This call deletes the message with the specified unique id.
  98.    A message may be deleted until it has been successfully received,
  99.    and may be deleted by any application which can provide the
  100.    id for the message.
  101.    
  102.    Errors:
  103.    fnfErr: no message exists with the specified id
  104.                                                                        */
  105.